<!DOCTYPE html>
<html><head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
	<meta charset="UTF-8">
	<title>README</title>
	<style>
		body {
			margin-bottom: 50px;
		}
		.list_indent {
			padding-left: 2em;
		}
		code {
			padding-left: 2px;
			padding-right: 2px;
			background: hsl(220, 80%, 90%);
		}
		.implemented {
			font-size: 70%;
			padding-left: 2px;
			padding-right: 2px;
			background: hsl(120, 80%, 90%);
		}
		.planned {
			font-size: 70%;
			padding-left: 2px;
			padding-right: 2px;
			background: hsl(60, 80%, 90%);
		}
		.optional {
			background: #fff71c;
			padding-left: 2px;
			padding-right: 2px;
			width: 90px;
		}

	</style>
</head>
<body>
	<h1>Compilers</h1>
	<h4><i>Luuk van Sloun &amp; Atisha Ribeiro</i></h4>
	<br>
	<h3>Project Structure</h3>
	<ul>
		<li><b>Grammar</b></li>
		<span class="list_indent">
			The grammar is specified in <code>C_Grammar.g4</code>.
		</span>
		<li><b>AST</b></li>
		<div class="list_indent">
			There are 2 classes located in <code>AST.py</code>: The <code>AST</code> class and the <code>GrammarListener</code> class.<br/>
			<code>AST</code> is just a node class that has children nodes. Each node stores 3 values:<br/>
			<ul>
				<li><code>name</code>: specifies the node type (e.g. function)</li>
				<li><code>value</code>: specifies the node value (e.g. main)</li>
				<li><code>type</code>: specifies the variable type (e.g. int)</li>
			</ul>
			The class also contains a <code>to_dot()</code> function to visualise the AST.<br/>
			<code>GrammarListener</code> contains an AST object and fills it as it traverses the derivation tree generated by ANTLR.<br/>
		</div>
		<li><b>Symbol Table</b></li>
		<div class="list_indent">
			The <code>SymbolTable</code> class is located in <code>SymbolTable.py</code>.<br/>
			It uses DFS to traverse the AST and fill in the symbol table. While traversing, it checks if variables are declared only once and if variables used have been declared previously.
			If these checks fail, an exception is thrown.<br/>
			The class also contains a <code>to_dot()</code> function to visualise the symbol table.<br/>
		</div>
		<li><b>Code Generation</b></li>
		<div class="list_indent">
			The <code>CodeGenerator</code> class is located in <code>MIPSGenerator.py</code>.<br/>
			Traverses the AST recursively with DFS and writes the MIPS code to a file.
		</div>
		<li><b>Code Liveness</b></li>
		<div class="list_indent">
			The <code>LivenessControl</code> class is located in <code>LivenessControl.py</code>.<br/>
			Goes over the code and checks the liveness of variables. Useless assignments are removed from the code.
		</div>
	</ul>

	<h3>Features</h3>
	<ul>
		<li><b>Types</b> <span class="implemented">implemented</span></li>
		<li><b>Import</b> <span class="implemented">implemented</span></li>
		<div class="list_indent">
			<code>printf</code> and <code>scanf</code> are declared when <code>#include &ltstdio.h&gt</code> is specified.
		</div>
		<li><b>Reserved Words</b> <span class="implemented">implemented</span></li>
		<li><b>Local and global variables</b> <span class="implemented">implemented</span></li>
		<li><b>Comments</b> <span class="implemented">implemented</span></li>
		<li><b>Operations</b> <span class="implemented">implemented</span></li>
		<ul>
			<li><b>Basic Comparison Operators</b> <span class="implemented">implemented</span></li>
		</ul>
		<li><b>Functions</b> <span class="implemented">implemented</span></li>
		<div class="list_indent">
			exception thrown when there is no main() present in the code.
		</div>
		<li><b>Arrays</b> <span class="implemented">implemented</span></li>

		<h4 class="optional">Optionals</h4>
		<li><b>Conversions</b> <span class="implemented">implemented</span></li>
		<div class="list_indent">
			casts implicitly when there is a type mismatch
		</div>
		<li><b>For loop</b> <span class="implemented">implemented</span></li>
		<li><b>Unary Operations <code>+</code> and <code>-</code></b> <span class="implemented">implemented</span></li>
		<li><b>Assignment Operators</b> <code>+=</code>, <code>-=</code>, <code>*=</code> and <code>/=</code> <span class="implemented">implemented</span></li>
		<li><b>Extra Comparison Operators</b> <code><=</code>, <code>>=</code> and <code>!=</code> <span class="implemented">implemented</span></li>
		<li><b>Check all paths in function body for return (except void func)</b> <span class="implemented">implemented</span></li>

	</ul>

	<h3>Optimisations</h3>
	<ul>
		<li><b>Unreachable/Dead code</b> <span class="implemented">implemented</span></li>
		<div class="list_indent">
			statements that do not change variables (like <code>a + 2;</code>) are also not generated.
		</div>

		<h4 class="optional">Optionals</h4>
		<li><b>No initialization of variables without initializer </b> <span class="implemented">implemented</span></li>
		<div class="list_indent">
			except for arrays, which are filled with zeroes
		</div>
		<li><b>Variable liveness </b> <span class="implemented">implemented</span></li>
		<div class="list_indent">
			variables that are not used after an assignment give a warning and the useless assignment is removed from the code
		</div>
		<li><b>Constant folding </b> <span class="implemented">implemented</span></li>
	</ul>

	<h3>Usage</h3>
	<ul>
		<li><b>Building</b></li>
		<div class="list_indent">
			To build the C compiler classes type <code>bash build</code>.<br/>
			This will also compile an example file <code>c_prog</code>, which will be written to <code>mips_prog</code>.
		</div>
		<li><b>Using <code>c2mips.py</code></b></li>
		<div class="list_indent">
			To run c2mips execute the following: <code>python3 c2mips.py &#60;inputfile&#62; &#60;outputfile&#62;.</code><br/>
			Useless assignments are removed by default. If you want to keep them use the <code>-s</code> argument: <code>python3 c2mips.py -s &#60;inputfile&#62; &#60;outputfile&#62;.</code>
		</div>
		<li><b>AST & SybmolTable dot file</b></li>
		<div class="list_indent">
			All dot files are created in the folder <code>/dotfiles</code>.
		</div>
		<li><b>Testing</b></li>
		<ul>
		<li>Working test files</li>
		<div class="list_indent">
			To run the files that showcase the implemented features, type <code>bash test</code>.<br/>
			.Dot files are not converted to png's here, they have to be converted manually
		</div>
		<li>Error test files</li>
		<div class="list_indent">
			These files showcase exceptions we have implemented. Since they throw an exception, they have to be executed one by one.
		</div>
		</ul>
	</ul>


</body></html>
